/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */

package com.wider.foundation.concurrency;

import java.util.Queue;

/**
 * This interface defines a standard framework for user to design its class which needs the knowledge of whether it's being queued as well as which queue it's being in.
 *
 * @author William Choi <avextk@gmail.com>
 */
public interface QueuingAware {
    /**
     * Action the instance of the implementation will take while being enqueued.
     * @param q The destination queue.
     */
    public void enterQueue(Queue q);

    /**
     * Action the instance of the implementation will take while being dequeued.
     * @param q The destination queue.
     * @return  True if succeeded; false otherwise.
     */
    public boolean exitQueue(Queue q);

    /**
     * Method to have the instance of the implementation to force to remove itself from the queue.
     * @param q The destination queue.
     * @return  True if succeeded; false otherwise.
     */
    public boolean leaveQueue(Queue q);

    /**
     * Method for checking if this instance of the implementation is being queued.
     * @return  True if so; false otherwise.
     */
    public boolean isQueued();

    /**
     * Method for leaving all the related queues at once.
     * @return  The number of queues we left.
     */
    public long leaveAllQueues();
}
